SAS Environment Manager: Importing events

An important goal of SAS Environment Manager is to communicate with existing software systems. This capability includes not only monitoring other non-SAS platform resources, but also means having the ability to respond to events from outside the SAS platform. We’ve seen how SAS Environment Manager can generate an event for external consumption (see Scott McCauley’s blog on Exporting events from SAS Environment Manager), but we can also have SAS Environment Manager import an event that was generated by an external source.

First, before we discuss methods for importing events, it’s important to understand that events are not alerts. An alert is just one type of system event among several. Events can be any of the following:

log entries for errors (if log tracking is ON for a particular resource)
other log entries that you specify
server start/stop/restart
configuration changes (if configuration tracking is ON)
any alert

To generate a new external event, the source may be anything as long as it has some small programmable capability. In this post, I will illustrate how create and import them using simple SAS data step code.

Start by creating a platform service resource

If you have the SAS Environment Manager Service Architecture Framework initialized, then you will already have a platform service resource called “EMI Framework Event Importer”. If not, you can quickly create an “event importer” type of object as follows. From the SAS Environment Manager interface:

Select Resourcesà Browseà Platforms and select one of the available machines
Select Tools Menuà New Platform Service and supply the following information:
- Name: Event Importer (or any name you wish)
- Desc: (anything you wish)
- Service Type: SAS Event Importer
Click OK
On the new screen select Configuration Properties
With the following screen, make sure that the following properties are set as illustrated here. When completed, select OK.

Generating events entries with SAS macro

Once you have an operating event importer, you can use a simple SAS macro “%evevent” to generate the event, which will consist of one line in a text file, formatted as follows:

DateTime stamp | Message Level | Source of Message |  Message Text

By default, the file emi-framework\Events\sasev.events contains all events, one per line, and is scanned by the SAS Environment Manager for new events as they occur. Here’s a small SAS program illustrating the use of the %evevent macro:

%include "D:\SAS\Config\Lev1\Web\SASEnvironmentManager\emi-framework\SASMacros\evevent.sas";
%let sasevconfigdir=D:\SAS\Config\Lev1\Web\SASEnvironmentManager\emi-framework;
%let evdebug=1;
%evevent(src=SDA:NVP,msglevel=INFO,msgtext="This is an externally generated event") ;

I used the SAS Display Manager to execute this code, from the machine where the SAS Environment Manager is installed. The macro will write out events to the file sasev.events, in the directory specified above. The macro %evevent is documented in the SAS Environment Manager User’s Guide 2.4.

Calling the macro from shell script

You’ll notice that in the above program I had to specify the macro library, the correct configuration directory for the SAS emi-framework, and a debug flag, before calling the macro. To avoid all this and have this environment created for you, you can call your program from another shell program, runSASJob.bat (sh) found in the /emi-framework/bin directory. In this case, you create a one-line SAS program (CreateEvent.sas), which simply contains:

%evevent(src=SDA:NVP,msglevel=INFO,msgtext="This is an externally generated event") ;

Then, from the same \bin directory, issue the following command and you should get the same results.

runSASJob.bat CreateEvent.sas

To check on the success of these scripts, you can look in the file sasev.events. You will see the lines similar to the following (along with events generated by the EMI Framework running the ETL jobs overnight):

2015-03-19T02:00:28-0400|INFO|EMI Framework|createGroups ran
20150319T123042+0000|INFO|SDA:NVP:NVP|userid=sas message="This is the freeform text of the message"
2015-03-20T00:00:50-0400|INFO|EMI Framework|createGroups ran
2015-03-20T01:00:35-0400|INFO|EMI Framework|createGroups ran
2015-03-20T02:00:35-0400|INFO|EMI Framework|createGroups ran
20150320T160002+0000|INFO|SDA:NVP:NVP|userid=sas message="This is an externally generated event"
20150320T160225+0000|INFO|SDA:NVP:NVP|userid=sas message="This is an externally generated event"

And of course, the new events should show up in the SAS Environment Manager interface, Event Center:

Using the Framework command line

By the way, there is also a command-line version of this function. In the emi-framework/bin directory, you can execute the following script:

create_event.bat -l INFO -s DWN:NVP -v "This event is created by the batch file script"

If you issue this command with the -h parameter, you will see a display of all command options.

The scanner that parses the sasev.events file runs with a frequency between less than a minute (for a single machine or small installation) up to a maximum of 5 minutes on a large and complex installation.

[Note: you may have noticed that the events written by the ETL processes have a slightly different format than the events written by our script. This is known defect, but as long as the events are imported into SAS Environment Manager correctly, they will function properly.]

Blogs